PocoScript Help

General

Scripting in Poco is implemented through PocoScript, an interpreted language created for Poco that focuses on mail processing and handling. Even though it has a narrow focus, PocoScript can act as a conduit between Poco and other applications to implement more sophisticated mail processing, such as mail encryption.

PocoScript is interpreted, high-level language, run directly by the Poco executable. Language syntax is simple, specifically focused at handling e-mail messages. Since the interpreter is part of the main application, to run any scripts you need to have Poco running.

Script is run either on selected messages or on Incoming/Outgoing messages.

Variables

PocoScript is not a strongly typed language, but it offers four basic variable types. Variables can have any alphanumeric name, prefixed with the type identifier, listed below:

$ - String variable

# - Numeric variable

% - Mail message variable

& - Boolean variable

String types can be assigned out of their type, but the assignment will be successful only if the values are interchangeable. This means that you can assign an integer variable to a string variable at any time, but the reverse will work only when the string contains a true integer. As the script environment was designed to run unattended, badly typed assignments will simply fail.

PocoScript provides several system variables at run time with already assigned values, you can use in your programs:

$mailpath = Full path to mailboxes root folder

$scriptpath = Full path to scripts folder

$apppath = Full path to application root folder

$attachpath = Full path to attachments folder

$addresspath = Full path to address books folder

$sigpath = Full path to signatures folder

$temppath = Full path to Windows temporary folder

%message = Contains the message passed to the script to be processed. It is either a selected message that script is run on, or a currently incoming or outgoing message. The %message variable can be modified at run-time, but changes are only passed back to Poco when run on incoming or outgoing mail. When %message is modified while script is running on selected messages, the changes will not affect the original message in the mailbox.

Boolean variables (&var) can be used in several forms, all of which resolve to logical true or false. Value "True", "Yes", "On" or digit "1" all resolve to true, while "False", "No", "Off" or digit "0" resolve to false. Any other assignments to a boolean variable will resolve to true, such as number "42" or string "Friday". Boolean variables are not strongly typed, so you can assign an integer or a string to them. You can apply boolean operators to boolean variables, see Operators section. Boolean variables resolved by the interpreter will always resolve as "1" for true and "0" for false, and as such can be assigned to integer or string variables.

Message variables (%var) consist of message header fields and message body. You can use a set of message commands to operate on message variables. They will allow you to operate on messages as a whole, as well as access individual headers, or save them to a file / mailbox.

When assigning values to string variables, place them in double-quotes to ensure they are fully assigned. If you are assigning a single word, without spaces or separators, you don't need to use quotes.

Operators

Most of the operations on the variables are done through built-in commands, including basic addition and subtraction. Exception is the boolean operators. They take form of

value/variable OPERATOR value/variable

These expressions are used mainly in assignment commands, like SET, and in boolean commands, like IF. Following operators can be used:

> Greater than, works for integers and strings. String are compared alphabetically;

< Less than, usage same as >;

= Equals, evaluates true only for equal integers and EXACTLY identical strings;

! Does not equal, usage same as =;

^ Contained within, works practically only on strings. Evaluates true if the first string is contained within the second string.

When applied to strings, all boolean operators are case sensitive. To ignore the case of the compared strings, apply Lowercase or Uppercase commands to the values before the comparison.

Files

PocoScript is fairly adept at handling text files. PocoScript does not support binary files. When opening and saving files, the default directory used is the root directory of your mail folder, or as described above %mailpath. To save outside the default directory, simply use fully qualified file names.

When saving files, the default settings will overwrite any existing files. To change that set AppendToFile to true at the beginning of the script. For instance, if you want to save three messages to a new mailbox call "Stuff", simply run

AppendToFile true
SaveMessage %m1 Stuff.mbx
SaveMessage %m2 Stuff.mbx
SaveMessage %m3 Stuff.mbx

And that is it. This will create a valid mailbox that you can later open with Poco.

Error Handling

If PocoScript encounters a runtime error while parsing the script, it will do its best to continue running the script without halting. If you want to control what happens when an error is encountered, you can use the following variables:

$OnErrorMessage: if you define this variable with a non-empty value, Poco will present that message whenever error occurs, with the correct error description below and the line that caused the error.

$OnErrorGoTo: if this variable is defined, when Poco encounters an error the script execution will continue on the label defined by this variable.

For example, to display a message "Sorry, error occurred", and continue script execution on script section with label ":ErrorHandler", define the following at the point in the script you wish to activate error handling (usually the beginning of the script):

Set $OnErrorMessage "Sorry, error occurred"
Set $OnErrorGoTo "ErrorHandler"

In addition to these variables, Poco will set the following variables to the corresponding values AFTER the error occurs:

#ErrorResult: Numerical value of the error (see below)
$ErrorResult: Text description of the error message
#ErrorLine: Line number where the error occurred
$ErrorLine: Line itself that the error occurred on

Following are currently recognized and handled runtime errors and the corresponding codes used for #ErrorResult:

FILE I/O ERRORS
1010 Error saving message to file
1012 Error saving text
1014 Error saving text to new file
1020 Error reading file
1025 Error reading file - file not found

MATH OPS ERRORS
1110 Integer operation on string
1112 Float operation on string
1120 Divide by zero

RUNTIME ERRORS
1210 Non-integer parameter in integer variable
1220 Invalid date parameter
1230 Invalid time parameter

ONLINE ERRORS
1310 Sending message failed

Back to Poco Help : PocoScript Index : Top

Commands

Creates a blank message.

Loads a message saved to a file in RFC822 format.

Saves message in RFC822 format.

Deletes message passed to the script. Practically used only on %message variable; when used on messages instanced by the script, it will only add "D" to the Status header.

Sends the prepared message %m via SMTP server setup in the accounts or settings. This command sends immediately, if you want to queue message to be sent later, simple set AppendToFile True and SaveMessage %m Out.mbx.

Message %m is opened in Poco to be edited and or possibly sent/queued. EditMessage will not interpret styled text if itís in the message, and will extract plain text without formatting tags.

Prints the message %m to the current printer. Message is formatted for printing with the current printing template.

Marks the message %m to be encrypted, which happens whenever the message is saved to disk. When run on Incoming or Outgoing messages the command will read the encryption password from the Accounts Setup for that particular account. When the filter is run on Selected Messages it will use the currently set encryption password (see SetEncryptionPassword command).

Sets the current encryption password to the passed value. For security reasons it is best to ask the user for the password with MessageBox command, rather than saving it as clear text in the script. There is no ReadEncryptionPassword command that returns the current password, also for security reasons!

Adds a "header" to message %m with value of $a. Works only on single-line headers. Donít use these commands to add message recipients ñ better support for that is provided by commands AddTo, AddCC and AddBCC. SetHeader and AddHeader behave the same way, SetHeader is still supported for backward compatibility while AddHeader is semantically correct.

Deletes the passed header from the message %m.

Reads "header" value of message %m into variable $a. Works only on single-line headers.

Places all of the message %m headers into a multiline variable $a, just as they would appear in an RFC 822 message, complete with header names.

Adds a primary recipient to message %m.

Adds a carbon copy recipient to a message %m.

Adds an anonymous recipient to a message %m.

Clears all primary recipients.

Clears all carbon copy recipients.

Clears all anonymous recipients.

Places all the primary recipients into $a.

Places all the carbon copy recipients into $a.

Places all the anonymous recipients into $a.

Opens text file and places it in variable $a. The file may contain line breaks.

Saves variable $a to a text file.

Deletes the message body for message %m.

Appends two strings with a line separator. Primary used on multiline string variables, like message body.

Appends signature of the current account to the message %m. Signature is parsed at this point for any inserted user tags (see Signatures). To change the current account see SetAccount.

Assigns variable $a as a body of message %m.

Assigns body of message %m to variable $a. If message %m is of content type text/html, ReadBody will place the plain text version of the body into $a, without any formatting. The actual message %m will not be changed in either case.

Assigns body of message %m as raw text to variable $a, regardless of message %m content type.

It will "quote" or insert quotestring as the beginning of each line of variable $a. quotestring is optional and if left out "greater than" sign is used.

Removes leading quotestring from each line of $a. Reverses QuoteBody. If quotestring is not specified, "greater than" symbol is assumed.

Extract person's name from properly formatted e-mail address entry, like "Jane Doe <jdoe@provider.com>". Result overwrites the original value in $a.

Just like the ExtractName, but instead extracts the e-mail address.

Reads CSV formatted data in $b, and parses each record as a separate line in $a.

Reads a multiline variable $b and formats each line as a single record. Places the CSV formatted records as a single line into $a.

Reads the list of attached files in the message %m, and places their filenames with full path into $a. Each file is placed onto a separate line in $a. This command works by scanning the end of the message for string
Attachment Converted: "filename"
which Poco places at the end of the message when an attachment is received with a message.

Places the name of the current account in $a.

All of these commands read the respective values for the current account and place them in the variable $a.

Sets which account to use as the current account. This command will affect all of the account reading or setting commands described.

SetAccountTag $a

All of these commands will permanently set the respective value for the current account.

Set &a bool-expression

All Set commands will assign the value on the right to the variable on the left. Right side can be a value ("John") or a variable ($date). You can assign out of type, just be careful when you use those values later on.

All External commands work similar to Set, they assign value to a variable, except they cannot assign a variable to a variable, and the External declarations will show up on the Setup tab of the Scripts. You can only use $userdata1 through $userdata4 and $userfile1 through $userfile4 for variable names if you want Poco to display them to the user. For each $userdata Poco will display an edit field with the description "desc" in the Setup pane of the Filters and Scripts window. Each $userfile will map a button on the same pane to the filename in "value". When user clicks on that button, Poco will launch Notepad with that file loaded. Please take a look at the sample scripts provided for demonstration.

Use InputBox when you want to prompt the user for a value. A window will pop up with question in "desc", and with a default value filled out as "value". User can edit the value, as well as cancel the script at this point. Do not use InputBox in time sensitive operations, as it stops the script execution until user tells it to proceed. The value will be placed in $a.

InputBox also features a drop-down edit box which you can use to pre-fill selections for the user. You can use standard tags for the setup window in the description to populate the drop-box, for example with the list of headers. These tags are: %mailboxes%, %bool%, %accounts%, %headers%. You can also use the new tag %var% that is user definable. These tags have to appear in the description text in order for Poco to use them. The new %var% tag works by parsing the default value for pipe or "|" sign. A simple example: InputBox $a "Test box...%var%" "First choice|2nd|3rd".

Embed command allows you to embed multiline values within the script itself. Anything following the Embed command is considered as value to be placed in $a. Use the $b to mark when the input will finish; for instance command

Embed $a "@@@"

Adds all the strings together and places the result in $a. Integers are added as strings.

Adds integers and places the result in #a. Non-integers are interpreted as zero.

Multiplies the two and places the result in #a. Non-integers are interpreted as one.

Division. Non-integers are interpreted as one. Division by zero returns zero.

Subtraction. Non-integers are interpreted as zero.

It will delete substring $b from $a.

Places a random number into variable #a, in a range from 0 to #n (0 <= x < #n).

These commands are the standard trigonometry operations sine, cosine and tangent and are performed in radians. Each command takes the argument in $b and returns the value in $a variable. They use string variables, since they operate on floating point values. If the functions fail (for example if an invalid number is passed) they will return an empty string. The result will be accurate to 8 decimal places.

Increase the value of #a by 1.

Decrease the value of #a by 1.

Above are all boolean operations, on boolean variables. Result is placed in the first variable.

Converts the string to lowercase or uppercase.

Trims left and right spaces from string $a.

Trims left and right spaces from every line in multiline variable $a.

Inserts string $b into variable $a at the position #n in characters. If #n is larger than the size of $a, the the string is appended to the back of $a. Character positions are one-based, meaning the first character has a position of 1.

Acts identical to InsertString, except it works with lines on multiline variable $a, rather than characters. Line positions are zero-based, meaning the first line has a position of 0.

Returns in #n the position in characters of string $b inside string $a. Character numbers are 1-based!

Returns in #n the number of characters in $a. Character numbers are 1-based!

Returns in #n the line number of multiline variable $b, where $a appears. Line numbers are zero-based!

Returns in #n the number of lines in $a. Line numbers are zero-based!

Places line number #n of multiline variable $b into $a. Line numbers are zero-based!

Deletes a portion of string $a, starting from position #n, and deleting the next #c characters. Character numbers are 1-based!

Returns in $a the single character at the position #n in $b. Character numbers are 1-based!

Returns true if variable #b/$b/&b contains a number that can be further processed. Otherwise returns false. Due to relaxed variable typing of PocoScript, you can assign a non-integer variable to a number variable like #b. Use this function in those cases.

Similar to IsNumber, but checks for boolean values in the second parameter. Boolean values are 1, 0, true, false, on, off, yes, no. They are not case sensitive. If a value is not boolean, it will still evaluate to true when tested.

GetTime $a

Places current date or time in $a.

Calculates the difference in days between dates in $b and $c and puts the result in #a. Order of $b and $c is irrelevant - the result is always positive, except when an invalid date is in either $b or $c; the result is then -1.

External Commands

Use AppendToFile to modify saving to file. When set to true, if file already exists, saved information is appended to the file. When set to false, if file exists it is overwritten with saved information. This variable defaults to false when the script is started.

Starts an external application specified in "file". The application name has to be either fully qualified or in the windows search path. If you want to pass any parameters to the application, use the optional "params" parameter. Executable name and parameters need to be separated for parameters to be passed correctly. You can also pass non-executable filename - as long as it is registered with Windows correctly, Poco will launch the viewer application on that file. Yes, you can also launch fully qualified URLs, such as http or even mailto.

Works identical to Execute, but unlike Execute, ExecuteAndWait will stop Pocoís operation and script until the external process is finished. Obviously, caution needs to be exercised when using this command, but it is a great help when running external message processors, such as message encryption.

PlaySound will play a WAV file specified by "file". If you pass the literal "user", PlaySound will instead play the sound defined by the user, in Program Settings. Passing the literal "system" will play the built-in New Mail sound.

Shows the informational dialog box with an OK button. Text in $a is used for the message.

Sounds the Windows system beep, as defined by the user.

Stops the execution of the script for #n seconds.

Affects the main application window, it will refresh the mailboxes currently showing in Mailboxes window. Use it when you have just created or deleted a mailbox, to keep the application in-sync. If not used, Poco will pick up the new mailboxes on restart, or if user right-clicks and chooses Refresh.

Deletes a file if it exists.

If the file exists, &a is set to true, otherwise it is set to false.

Places the size of file in bytes into a variable #a. If the file doesn't exist #a will become 0.

Attaches the file to the message %m. If the file doesn't exist the message is unchanged.

Lists the contents of the directory dir and places it into multiline variable $a. There are two optional parameters: $pattern is a string that will be used to filter matching files. If omitted "*.*" is assumed. #mode denotes the type of files to list, it defaults to 47 if omitted. Mode can be one of the following values:
1: Read-only files
2: Hidden files
4: System files
8: Volume ID files
16: Directory files
32: Archive files
63: Everything
You can add numbers to further specify files, for example mode 63 will include all files and directories, while mode 47 will include only all files but not directories.

Copies to clipboard value contained in variable $a or the value directly.

Pastes the contents of the clipboard (text only) into variable $a.

Continues the execution of the program at "label" if expression evaluates to true.

Forces execution to jump to "label"

Marks the line for branching instructions. Note that the actual label name is preceded with a colon.

Terminates the execution of the script.